• 错误处理
    • 内容列表
    • 基础" level="2">基础
      • 理解 unwrapping" level="3">理解 unwrapping
      • Option类型" level="3">Option类型
        • 组合Option<T>值" level="4">组合Option<T>
      • Result类型" level="3">Result类型
        • 解析整型" level="4">解析整型
        • Result类型别名习惯" level="4">Result类型别名习惯
      • 小插曲:unwrapping 并不邪恶" level="3">小插曲:unwrapping 并不邪恶
    • 处理多种错误类型" level="2">处理多种错误类型
      • 组合OptionResult" level="3">组合OptionResult
      • 组合的限制" level="3">组合的限制
      • 提早返回" level="3">提早返回
      • try!宏" level="3">try!
      • 定义你自己的错误类型" level="3">定义你自己的错误类型
    • 用于错误处理的标准库 trait" level="2">用于错误处理的标准库 trait
      • Errortrait" level="3">Errortrait
      • Fromtrait" level="3">Fromtrait
      • 真正的try!宏" level="3">真正的try!
      • 组合自定义错误类型" level="3">组合自定义错误类型
      • 给库编写者的建议" level="3">给库编写者的建议
    • 案例学习:一个读取人口数据的程序" level="2">案例学习:一个读取人口数据的程序
      • 初始化" level="3">初始化
      • 参数解析" level="3">参数解析
      • 编写逻辑" level="3">编写逻辑
      • 使用Box<Error>处理错误" level="3">使用Box<Error>处理错误
      • 从标准输入读取" level="3">从标准输入读取
      • 用自定义类型处理错误" level="3">用自定义类型处理错误
      • 增加功能" level="3">增加功能
    • 精简版" level="2">精简版

    错误处理

    error-handling.md


    commit e89eee11744dee6dd13ff146817cdd4075952a0a

    就像大多数编程语言,Rust 鼓励程序猿以特定的方式处理错误。一般来讲,错误处理被分割为两个大类:异常和返回值。Rust 选择了返回值。

    在这一部分,我们试图提供一个全面的 Rust 如何处理错误的解决方案。不仅如此,我们也尝试一次一点的介绍错误处理,这样当你离开时会有一个对所有东西如何协调的坚实理解。

    Rust 的错误处理天生是冗长而烦人的。这一部分将会探索这些坑并展示如何使用标准库来让错误处理变得准确和符合工程原理。

    内容列表

    这一部分灰常的长,大部分因为我们从最基础的和类型和组合入手,并尝试一点一点的解释 Rust 错误处理的动机。为此,对有其他类似类型系统经验的童鞋可能想要跳过一些内容。

    基础" class="reference-link">基础

    你可以认为错误处理是用事例分析(case analysis)来决定一个计算成功与否。如你所见,工程性的错误处理就是要减少程序猿显式的事例分析的同时保持代码的可组合性。

    保持代码的可组合性是很重要的,因为没有这个要求,我们可能在遇到没想到的情况时panic。(panic导致当前线程结束,而在大多数情况,导致整个程序结束。)这是一个例子:

    1. // Guess a number between 1 and 10.
    2. // If it matches the number we had in mind, return `true`. Else, return `false`.
    3. fn guess(n: i32) -> bool {
    4. if n < 1 || n > 10 {
    5. panic!("Invalid number: {}", n);
    6. }
    7. n == 5
    8. }
    9. fn main() {
    10. guess(11);
    11. }

    如果你运行这段代码,程序会崩溃并输出类似如下信息:

    1. thread 'main' panicked at 'Invalid number: 11', src/bin/panic-simple.rs:5

    这是另一个稍微不那么违和的例子。一个接受一个整型作为参数,乘以二并打印的程序。

    1. use std::env;
    2. fn main() {
    3. let mut argv = env::args();
    4. let arg: String = argv.nth(1).unwrap(); // error 1
    5. let n: i32 = arg.parse().unwrap(); // error 2
    6. println!("{}", 2 * n);
    7. }

    如果你给这个程序 0 个参数(错误 1)或者 第一个参数并不是整型(错误 2),这个程序也会像第一个例子那样 panic。

    你可以认为这种风格的错误处理类似于冲进瓷器店的公牛。它会冲向任何它想去的地方,不过会毁掉过程中的一切。

    理解 unwrapping" class="reference-link">理解 unwrapping

    在之前的例子中,我们声称程序如果遇到两个错误情况之一会直接 panic,不过,程序并不像第一个程序那样包括一个显式的panic调用。这是因为 panic 嵌入到了unwrap的调用中。

    Rust 中“unwrap”是说,“给我计算的结果,并且如果有错误,panic 并停止程序。”因为他们很简单如果我们能展示 unwrap 的代码就更好了,不过在这么做之前,我们首先需要探索OptionResult类型。他们俩都定义了一个叫unwrap的方法。

    Option类型" class="reference-link">Option类型

    Option类型定义在标准库中

    1. enum Option<T> {
    2. None,
    3. Some(T),
    4. }

    Option类型是一个 Rust 类型系统用于表达不存在的可能性possibility of absence)的方式。将不存在的可能性编码进类型系统是一个重要概念,因为它会强迫编译器处理不存在的情况。让我们看看一个尝试在一个字符串中找一个字符的例子:

    1. // Searches `haystack` for the Unicode character `needle`. If one is found, the
    2. // byte offset of the character is returned. Otherwise, `None` is returned.
    3. fn find(haystack: &str, needle: char) -> Option<usize> {
    4. for (offset, c) in haystack.char_indices() {
    5. if c == needle {
    6. return Some(offset);
    7. }
    8. }
    9. None
    10. }

    注意当函数找到一个匹配的字符,它并不仅仅返回offset。相反,它返回Some(offset)Some是一个Option类型的一个变体或一个值构造器。你可以认为它是一个fn<T>(value: T) -> Option<T>类型的函数。同理,None也是一个值构造器,除了它并没有参数。你可以认为None是一个fn<T>() -> Option<T>类型的函数。

    这可能看起来并没有什么,不过这是故事的一半。另一半是使用我们编写的find函数。让我们尝试用它查找文件名的扩展名。

    1. # fn find(haystack: &str, needle: char) -> Option<usize> { haystack.find(needle) }
    2. fn main() {
    3. let file_name = "foobar.rs";
    4. match find(file_name, '.') {
    5. None => println!("No file extension found."),
    6. Some(i) => println!("File extension: {}", &file_name[i+1..]),
    7. }
    8. }

    这段代码使用模式识别来对find函数的返回的Option<usize>进行 case analysis。事实上,case analysis 是唯一能获取Option<T>中存储的值的方式。这意味着你,作为一个程序猿,必须处理当Option<T>None而不是Some(t)的情况。

    不过稍等,那我们之前使用的unwrap呢?那里并没有 case analysis!相反,case analysis 被放入了unwrap方法中。如果你想的话你可以自己定义它:

    1. enum Option<T> {
    2. None,
    3. Some(T),
    4. }
    5. impl<T> Option<T> {
    6. fn unwrap(self) -> T {
    7. match self {
    8. Option::Some(val) => val,
    9. Option::None =>
    10. panic!("called `Option::unwrap()` on a `None` value"),
    11. }
    12. }
    13. }

    unwrap方法抽象出了 case analysis。这正是unwrap的工程化用法。不幸的是,panic!意味着unwrap并不是可组合的:它是瓷器店中的公牛。

    组合Option<T>值" class="reference-link">组合Option<T>

    之前的例子中,我们看到了如何用find发现文件名的扩展名。当然,并不是所有文件名都有一个.,所以可能文件名并没有扩展名。不存在的可能性被编码进了使用Option<T>的类型。换句话说,编译器将会强制我们描述一个扩展名不存在的可能性。在我们的例子中,我们只打印出一个说明情况的信息。

    获取一个文件名的扩展名是一个很常见的操作,所以把它放进一个函数是很有道理的:

    1. # fn find(haystack: &str, needle: char) -> Option<usize> { haystack.find(needle) }
    2. // Returns the extension of the given file name, where the extension is defined
    3. // as all characters following the first `.`.
    4. // If `file_name` has no `.`, then `None` is returned.
    5. fn extension_explicit(file_name: &str) -> Option<&str> {
    6. match find(file_name, '.') {
    7. None => None,
    8. Some(i) => Some(&file_name[i+1..]),
    9. }
    10. }

    (专业建议:不要用这段代码,相反使用标准库的extension方法。)

    代码是简单的,不过重要的是注意到find的类型强迫我们考虑不存在的可能性。这是一个好事,因为这意味着编译器不会让我们不小心忘记了文件名没有扩展名的情况。另一方面,每次都像extension_explicit那样进行显式 case analysis 会变得有点无聊。

    事实上,extension_explicit的 case analysis 遵循一个非常常见的模式:将Option<T>中的值映射为一个函数,除非它是None,这时,返回None

    Rust 拥有参数多态(parametric polymorphism),所以定义一个组合来抽象这个模式是很容易的:

    1. fn map<F, T, A>(option: Option<T>, f: F) -> Option<A> where F: FnOnce(T) -> A {
    2. match option {
    3. None => None,
    4. Some(value) => Some(f(value)),
    5. }
    6. }

    事实上,map是标准库中的Option<T>定义的一个方法。值得一提的是,它有着一个略微不同的 signature:一个以self&self&mut self作为第一个参数的方法。

    用我们的新组合,我们可以重写我们的extension_explicit方法来去掉 case analysis:

    1. # fn find(haystack: &str, needle: char) -> Option<usize> { haystack.find(needle) }
    2. // Returns the extension of the given file name, where the extension is defined
    3. // as all characters following the first `.`.
    4. // If `file_name` has no `.`, then `None` is returned.
    5. fn extension(file_name: &str) -> Option<&str> {
    6. find(file_name, '.').map(|i| &file_name[i+1..])
    7. }

    我们通常会发现的另一个模式是为一个OptionNone时赋一个默认值。例如,也许你的程序假设即便一个文件没有扩展名则它的扩展名是rs。正如你可能想象到的,这里的 case analysis 并不特定用于文件扩展名 - 它可以用于任何Option<T>

    1. fn unwrap_or<T>(option: Option<T>, default: T) -> T {
    2. match option {
    3. None => default,
    4. Some(value) => value,
    5. }
    6. }

    与上面的map相似,标准库中的实现是一个方法而不是一个普通的函数。

    这里要注意的是默认值的类型必须与可能出现在Option<T>中的值类型相同。在我们的例子中使用它是非常简单的:

    1. # fn find(haystack: &str, needle: char) -> Option<usize> {
    2. # for (offset, c) in haystack.char_indices() {
    3. # if c == needle {
    4. # return Some(offset);
    5. # }
    6. # }
    7. # None
    8. # }
    9. #
    10. # fn extension(file_name: &str) -> Option<&str> {
    11. # find(file_name, '.').map(|i| &file_name[i+1..])
    12. # }
    13. fn main() {
    14. assert_eq!(extension("foobar.csv").unwrap_or("rs"), "csv");
    15. assert_eq!(extension("foobar").unwrap_or("rs"), "rs");
    16. }

    (注意unwrap_or是标准库中的Option<T>定义的一个方法,所以这里我们使用它而不是我们上面定义的独立的函数。别忘了看看更通用的unwrap_or_else方法。)

    还有另一个我们认为值得特别注意的组合:and_then。它让我们更容易地组合不同的代码来应对不存在的可能。例如,这一部分的很多代码是关于找到一个给定文件的扩展名的。为此,你首先需要一个通常截取自文件路径的文件名。虽然大部分文件路径都有一个文件名,但并不是都有。例如,.../

    所以,我们面临着从一个给定的文件路径找出一个扩展名的挑战。让我们从显式 case analysis 开始:

    1. # fn extension(file_name: &str) -> Option<&str> { None }
    2. fn file_path_ext_explicit(file_path: &str) -> Option<&str> {
    3. match file_name(file_path) {
    4. None => None,
    5. Some(name) => match extension(name) {
    6. None => None,
    7. Some(ext) => Some(ext),
    8. }
    9. }
    10. }
    11. fn file_name(file_path: &str) -> Option<&str> {
    12. // Implementation elided.
    13. unimplemented!()
    14. }

    你可能认为我们应该用map组合来减少 case analysis,不过它的类型并不匹配。。。

    1. fn file_path_ext(file_path: &str) -> Option<&str> {
    2. file_name(file_path).map(|x| extension(x)) // This causes a compilation error.
    3. }

    这里的map函数装箱了extension函数返回的Option<_>中的值,并且因为extension返回一个Option<&str>,表达式file_name(file_path).map(|x| extension(x))实际上返回一个Option<Option<&str>>

    不过因为file_path_ext仅仅返回Option<&str>(而不是Option<Option<&str>>),我们会遇到一个编译错误。

    被 map 函数作为输入的函数的返回值总是会被重新封装为Some。因此,我们需要一些像map,不过允许调用者直接返回一个Option<_>而不用在再套上另一个Option<_>的函数。

    它的泛型实现甚至比map更简单:

    1. fn and_then<F, T, A>(option: Option<T>, f: F) -> Option<A>
    2. where F: FnOnce(T) -> Option<A> {
    3. match option {
    4. None => None,
    5. Some(value) => f(value),
    6. }
    7. }

    现在我们可以不用显式 case analysis 重写我们的file_path_ext函数了:

    1. # fn extension(file_name: &str) -> Option<&str> { None }
    2. # fn file_name(file_path: &str) -> Option<&str> { None }
    3. fn file_path_ext(file_path: &str) -> Option<&str> {
    4. file_name(file_path).and_then(extension)
    5. }

    边注:因为and_then本质上就像map不过返回一个Option<_>而不是Option<Option<_>>,它在一些其他语言中被称为flatmap

    Option类型有很多其他定义在标准库中的组合。过一遍这个列表并熟悉他们的功能是一个好主意 —— 通常他们可以减少你的 case analysis。熟悉这些组合将会得到回报,因为他们很多也为Result类型定义了实现(相似的语义),而我们接下来会讲Result

    组合使用像Option这样的符合工程学的类型来减少显式 case analysis。他们也是可组合的因为他们允许调用者以他们自己的方式处理不存在的可能性。像unwrap这样的方法去掉了选择因为当Option<T>None他们会 panic。

    Result类型" class="reference-link">Result类型

    Result类型也定义于标准库中

    1. enum Result<T, E> {
    2. Ok(T),
    3. Err(E),
    4. }

    ResultOption的高级版本。相比于像Option那样表示不存在的可能性,Result表示错误的可能性。通常,错误用来解释为什么一些计算会失败。严格的说这是一个更通用的Option。考虑如下类型别名,它的语义在任何地方都与真正的Option<T>相同:

    1. type Option<T> = Result<T, ()>;

    它把Result的第二个类型参数改为总是()(读作“单元”或“空元组”)。()类型只有一个值:()(没错,类型和值两个级别的术语表示是一样的!)

    Result类型是一个代表一个计算的两个可能结果的方式。通常,一个结果是期望的值或者“Ok”而另一个意味着非预期的或者“Err”。

    就像OptionResult在标准库中也定义了一个unwrap方法。让我们定义它:

    1. # enum Result<T, E> { Ok(T), Err(E) }
    2. impl<T, E: ::std::fmt::Debug> Result<T, E> {
    3. fn unwrap(self) -> T {
    4. match self {
    5. Result::Ok(val) => val,
    6. Result::Err(err) =>
    7. panic!("called `Result::unwrap()` on an `Err` value: {:?}", err),
    8. }
    9. }
    10. }

    这实际上与Option::unwrap的定义一样,除了它在panic!信息中包含了错误信息。这让调试变得简单,不过也要求我们为E类型参数(它代表我们的错误类型)添加一个Debug限制。因为绝大部分类型应该满足Debug限制,这使得它可以在实际中使用。(Debug简单的意味着这个类型有合理的方式可以打印出人类可读的描述。)

    OK,让我们开始一个例子。

    解析整型" class="reference-link">解析整型

    Rust 标准库中让字符串转换为整型变得异常简单。事实上它太简单了,以至于你可以写出如下代码:

    1. fn double_number(number_str: &str) -> i32 {
    2. 2 * number_str.parse::<i32>().unwrap()
    3. }
    4. fn main() {
    5. let n: i32 = double_number("10");
    6. assert_eq!(n, 20);
    7. }

    在这里,你应该对调用unwrap持怀疑态度。例如,如果字符串并不能解析为一个数字,它会 panic:

    1. thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: ParseIntError { kind: InvalidDigit }', /home/rustbuild/src/rust-buildbot/slave/beta-dist-rustc-linux/build/src/libcore/result.rs:729

    这是很难堪的,而且如果这在你所使用的库中出现了的话,可以理解你会很烦躁。相反,我们应该尝试在我们的函数里处理错误并让调用者决定该怎么做。这意味着改变double_number的返回值类型。不过改编成什么呢?好吧,这需要我们看看标准库中parse方法的签名:

    1. impl str {
    2. fn parse<F: FromStr>(&self) -> Result<F, F::Err>;
    3. }

    额嗯。所以至少我们知道了我们需要使用一个Result。当然,也可以返回一个Option。毕竟,一个字符串要么能解析成一个数字要么不能,不是吗?这当然是一个合理的方式,不过实现内部区别了为什么字符串不能解析成数字。(要么是一个空字符串,一个无效的数位,太大或太小。)因此,使用Result更有道理因为我们想要比单纯的“不存在”提供更多信息。我们想要表明为什么解析会失败。你应该尝试再现这样的推理,当你面对一个OptionResult之间的选择时。如果你可以提供详细的错误信息,那么大概你也应该提供。(我们会在后面详细讲到。)

    好的,不过我们的返回值类型该怎么写呢?上面定义的parse方法对所有不同的标准库定义的数字类型是泛型的。我们也可以(应该)让我们的函数也是泛型的,不过这回让我们享受显式定义的好处。我们只关心i32,所以我们需要寻找FromStr的实现(在你的浏览器中用CTRL-F搜索“FromStr”)和与它相关的类型`Err。这么做我可以找出具体的错误类型。在这个例子中,它是std::num::ParseIntError。最后我们可以重写函数:

    1. use std::num::ParseIntError;
    2. fn double_number(number_str: &str) -> Result<i32, ParseIntError> {
    3. match number_str.parse::<i32>() {
    4. Ok(n) => Ok(2 * n),
    5. Err(err) => Err(err),
    6. }
    7. }
    8. fn main() {
    9. match double_number("10") {
    10. Ok(n) => assert_eq!(n, 20),
    11. Err(err) => println!("Error: {:?}", err),
    12. }
    13. }

    这比之前有些进步,不过现在我们写的代码有点多了!case analysis 又一次坑了我们。

    组合是救星!就像Option一样,Result有很多定义的组合方法。ResultOption之间的常用组合有很大的交集。特别的,map就是其中之一:

    1. use std::num::ParseIntError;
    2. fn double_number(number_str: &str) -> Result<i32, ParseIntError> {
    3. number_str.parse::<i32>().map(|n| 2 * n)
    4. }
    5. fn main() {
    6. match double_number("10") {
    7. Ok(n) => assert_eq!(n, 20),
    8. Err(err) => println!("Error: {:?}", err),
    9. }
    10. }

    常见的组合Result都有,包括unwrap_orand_then。另外,因为Result有第二个类型参数,所以有一些只影响错误类型的组合,例如map_err(相对于map)和or_else(相对于and_then)。

    Result类型别名习惯" class="reference-link">Result类型别名习惯

    在标准库中,你可能经常看到像Result<i32>这样的类型。不过等等,我们定义的Result有两个类型参数。我么怎么能只指定一个呢?这里的关键是定义一个Result类型别名来对一个特定类型固定其中一个类型参数。通常固定的类型是错误类型。例如,我们之前的解析整数例子可以重写成这样:

    1. use std::num::ParseIntError;
    2. use std::result;
    3. type Result<T> = result::Result<T, ParseIntError>;
    4. fn double_number(number_str: &str) -> Result<i32> {
    5. unimplemented!();
    6. }

    为什么我们应该这么做?好吧,如果我们有很多可能返回ParseIntError的函数,那么定义一个总是使用ParseIntError的别名就比每回都写一遍要方便很多。

    这个习惯最突出的一点是标准库中的io::Result。通常,当你使用io::Result<T>,很明显你就是在使用io模块的类型别名而不是std::result的原始定义。(这个习惯也用于fmt::Result。)

    小插曲:unwrapping 并不邪恶" class="reference-link">小插曲:unwrapping 并不邪恶

    如果你一路跟了过来,你可能注意到我们花了很大力气反对使用像unwrap这样会panic并终止你的程序的方法。通常来说,这是一个好的建议。

    然而,unwrap仍然可以被明智的使用。具体如何正当化unwrap的使用是一个灰色区域并且理性的人可能不会同意。我会简述这个问题的一些个人看法。

    • 在例子和简单快速的编码中。有时你要写一个例子或小程序,这时错误处理一点也不重要。这种情形要击败unwrap的方便易用是很难的,所以它显得很合适。
    • 当 panic 就意味着程序中有 bug 的时候。当你代码中的不变量应该阻止特定情况发生的时候(比如,从一个空的栈上弹出一个值),那么 panic 就是可行的。这是因为它暴露了程序的一个 bug。这可以是显式的,例如一个assert!失败,或者因为一个数组越界。

    这可能并不是一个完整的列表。另外,当使用Option的时候,通常使用expect方法更好。expect做了unwrap同样的工作,除了expect会打印你给它的信息。这让 panic 的结果更容易处理,因为相比“called unwrap on a None value.”会提供一个信息。

    我的建议浓缩如下:运用你良好的判断。我的文字中并没有出现“永远不要做 X”或“Y 被认为是有害的”是有原因的。所有这些都是权衡取舍,并且这是你们程序猿的工作去决定在你的用例中哪个是可以接受的。我们目标只是尽可能的帮助你进行权衡。

    现在我们介绍了 Rust 的基本的错误处理,并解释了 unwrap,让我们开始更多的探索标准库。

    处理多种错误类型" class="reference-link">处理多种错误类型

    到目前为止,我看到了不是Option<T>就是Result<T, SomeError>的错误处理。不过当你同时使用OptionResult时会发生什么呢?或者如果你使用Result<T, Error1>Result<T, Error2>呢?我们接下来的挑战是处理不同错误类型的组合,这将会是贯穿本章余下部分的主要主题。

    组合OptionResult" class="reference-link">组合OptionResult

    到目前为止,我们讲到了为OptionResult定义的组合。我们可以用这些组合来处理不同的计算结果而不用进行显式的 case analysis。

    当然,在实际的代码中,事情并不总是这么明显。有时你遇到一个OptionResult的混合类型。我们是必须求助于显式 case analysis,或者我们可以使用组合呢?

    现在,让我们重温这一部分的第一个例子:

    1. use std::env;
    2. fn main() {
    3. let mut argv = env::args();
    4. let arg: String = argv.nth(1).unwrap(); // error 1
    5. let n: i32 = arg.parse().unwrap(); // error 2
    6. println!("{}", 2 * n);
    7. }

    基于我们新掌握的关于OptionResult和他们的组合的知识,我们应该尝试重写它来适当的处理错误这样出错时程序就不会 panic 了。

    这里的坑是argv.nth(1)产生一个Optionarg.parse()产生一个Result。他们不是直接可组合的。当同时遇到OptionResult的时候,解决办法通常是把Option转换为一个Result。在我们的例子中,缺少命令行参数(来自env::args())意味着我们的用户没有正确调用我们的程序。我们可以用一个String来描述这个错误。让我们试试:

    1. use std::env;
    2. fn double_arg(mut argv: env::Args) -> Result<i32, String> {
    3. argv.nth(1)
    4. .ok_or("Please give at least one argument".to_owned())
    5. .and_then(|arg| arg.parse::<i32>().map_err(|err| err.to_string()))
    6. .map(|n| 2 * n)
    7. }
    8. fn main() {
    9. match double_arg(env::args()) {
    10. Ok(n) => println!("{}", n),
    11. Err(err) => println!("Error: {}", err),
    12. }
    13. }

    这个例子中有几个新东西。第一个是使用了Option::ok_or组合。这是一个把Option转换为Result的方法。这个转换要求你指定当OptionNone时的错误。就像我们见过的其他组合一样,它的定义是非常简单的:

    1. fn ok_or<T, E>(option: Option<T>, err: E) -> Result<T, E> {
    2. match option {
    3. Some(val) => Ok(val),
    4. None => Err(err),
    5. }
    6. }

    另一个新使用的组合是Result::map_err。这就像Result::map,除了它映射一个函数到Result的 error 部分。如果Result是一个Ok(...),那么它什么也不修改。

    这里我们使用map_err是因为它对保证相同的错误类型(因为我们使用了and_then)是必要的。因为我们选择把Option<String>(来自argv.nth(1))转换为Result<String, String>,我们也必须把来自arg.parse()ParseIntError转换为String

    组合的限制" class="reference-link">组合的限制

    IO 和 解析输入是非常常见的任务,这也是我个人在 Rust 经常做的。因此,我们将使用(并一直使用)IO 和多种解析工作作为例子讲解错误处理。

    让我们从简单的开始。我们的任务是打开一个文件,读取所有的内容并把他们转换为一个数字。接着我们把它乘以2并打印结果。

    虽然我们劝告过你不要用unwrap,不过开始写代码的时候unwrap也是有用的。它允许你关注你的问题而不是错误处理,并且暴露出需要错误处理的点。让我们开始试试手感,再接着用更好的错误处理重构。

    1. use std::fs::File;
    2. use std::io::Read;
    3. use std::path::Path;
    4. fn file_double<P: AsRef<Path>>(file_path: P) -> i32 {
    5. let mut file = File::open(file_path).unwrap(); // error 1
    6. let mut contents = String::new();
    7. file.read_to_string(&mut contents).unwrap(); // error 2
    8. let n: i32 = contents.trim().parse().unwrap(); // error 3
    9. 2 * n
    10. }
    11. fn main() {
    12. let doubled = file_double("foobar");
    13. println!("{}", doubled);
    14. }

    (附注:AsRef<Path>被使用是因为它与std::fs::File::open有着相同的 bound。这让我们可以用任何类型的字符串作为一个文件路径。)

    这里可能出现三个不同错误:

    1. 打开文件出错。
    2. 从文件读数据出错。
    3. 将数据解析为数字出错。

    头两个错误被描述为std::io::Error类型。我们知道这些因为返回类型是std::fs::File::openstd::io::Read::read_to_string。(注意他们都使用了之前描述的Result类型别名习惯。如果你点击Result类型,你将会看到这个类型别名,以及底层的io::Error类型。)第三个问题被描述为std::num::ParseIntError。特别的io::Error被广泛的用于标准库中。你会一次又一次的看到它。

    让我们着手重构file_double函数。为了让这个函数可以与程序的其他组件组合,它必须不能在上述错误情况下 panic。事实上,这意味着它在任何操作失败时应该返回一个错误。我们的问题是file_double的返回类型是i32,它并没有给我们一个有效的报告错误的途径。因此,我们必须以把返回类型i32改成别的什么的开始。

    我们需要决定的第一件事:我们应该用Option还是Result?当然我们可以简单的选择Option。如果出现任何错误了,我们可以简单的返回None。它可以工作并且比 panic 好多了,不过我们可以做的更好。我们应该在错误发生时传递一些细节。因为我们想要表达错误的可能性,我们应该使用Result<i32, E>。不过E应该是什么呢?因为可能出现两种不同的错误,我们需要把他们转换为一种通用类型。其中之一就是String。让我们看看这如何影响我们的代码:

    1. use std::fs::File;
    2. use std::io::Read;
    3. use std::path::Path;
    4. fn file_double<P: AsRef<Path>>(file_path: P) -> Result<i32, String> {
    5. File::open(file_path)
    6. .map_err(|err| err.to_string())
    7. .and_then(|mut file| {
    8. let mut contents = String::new();
    9. file.read_to_string(&mut contents)
    10. .map_err(|err| err.to_string())
    11. .map(|_| contents)
    12. })
    13. .and_then(|contents| {
    14. contents.trim().parse::<i32>()
    15. .map_err(|err| err.to_string())
    16. })
    17. .map(|n| 2 * n)
    18. }
    19. fn main() {
    20. match file_double("foobar") {
    21. Ok(n) => println!("{}", n),
    22. Err(err) => println!("Error: {}", err),
    23. }
    24. }

    这些代码看起来有点难以理解。在能轻松编写这样的代码前可能需要更多一些实践。我们写代码的方式遵循跟着类型走following the types)。一旦我们把file_double的返回类型改为Result<i32, String>,我们就不得不开始寻找正确的组合。在这个例子中,我们只用到了三个不同的组合:and_thenmapmap_err

    and_then被用来连接多个计算,其中每一个都有可能返回一个错误。在打开文件后,还有另外两个可能失败的计算:从文件读取和把内容解析成数字。相应地,有两个and_then的调用。

    map用来把一个函数用于ResultOk(...)值。例如,最后一个map调用把Ok(...)值(它是一个i32)乘以2。如果在这之前出现了错误,这里的操作会被省略,因为map是这么定义的。

    map_err是让一切可以工作的关键。map_err类似map,除了它把一个函数用于ResultErr(...)值。在这个例子中,我们想要把所有的错误转换为一个类型:String。因为io::Errornum::ParseIntError都实现了ToString,我们可以调用to_string()去转换他们。

    说了这么多,代码仍然不好懂。掌握组合的应用是很重要的,不过他们也有限制。让我们尝试一个不同的方式:提早返回。

    提早返回" class="reference-link">提早返回

    我想利用前一章节的代码并用提早返回重写它。提早返回让你提前退出函数。我们不能在另一个闭包中从file_double提前返回,所以我们需要退回到显式 case analysis。

    1. use std::fs::File;
    2. use std::io::Read;
    3. use std::path::Path;
    4. fn file_double<P: AsRef<Path>>(file_path: P) -> Result<i32, String> {
    5. let mut file = match File::open(file_path) {
    6. Ok(file) => file,
    7. Err(err) => return Err(err.to_string()),
    8. };
    9. let mut contents = String::new();
    10. if let Err(err) = file.read_to_string(&mut contents) {
    11. return Err(err.to_string());
    12. }
    13. let n: i32 = match contents.trim().parse() {
    14. Ok(n) => n,
    15. Err(err) => return Err(err.to_string()),
    16. };
    17. Ok(2 * n)
    18. }
    19. fn main() {
    20. match file_double("foobar") {
    21. Ok(n) => println!("{}", n),
    22. Err(err) => println!("Error: {}", err),
    23. }
    24. }

    理性的同学可能不同意这个比使用组合的代码更好,不过如果你并不熟悉组合方式,这些代码阅读起来更简单。它通过matchif let进行了显式 case analysis。如果错误出现了,它简单的停止执行并返回错误(通过转换为一个字符串)。

    这难道不是倒退吗?之前,我们说过工程性的错误处理的关键是减少显式 case analysis,不过这里我们又退回到了显式 case analysis。这表明,有多种方式可以减少显式 case analysis。组合并不是唯一的方法。

    try!宏" class="reference-link">try!

    Rust 中错误处理的基石是try!宏。try!宏像组合一样抽象了 case analysis,不过不像组合,它也抽象了控制流。也就是说,它可以抽象我们之前看到的提早返回的模式。

    这是一个简单化的try!宏定义:

    1. macro_rules! try {
    2. ($e:expr) => (match $e {
    3. Ok(val) => val,
    4. Err(err) => return Err(err),
    5. });
    6. }

    实际的定义有一点复杂。我们会在后面详述。)

    使用try!宏让我们的最后的例子异常的简单。因为它为我们做了 case analysis 和提早返回,我们的代码更紧凑也更易于理解:

    1. use std::fs::File;
    2. use std::io::Read;
    3. use std::path::Path;
    4. fn file_double<P: AsRef<Path>>(file_path: P) -> Result<i32, String> {
    5. let mut file = try!(File::open(file_path).map_err(|e| e.to_string()));
    6. let mut contents = String::new();
    7. try!(file.read_to_string(&mut contents).map_err(|e| e.to_string()));
    8. let n = try!(contents.trim().parse::<i32>().map_err(|e| e.to_string()));
    9. Ok(2 * n)
    10. }
    11. fn main() {
    12. match file_double("foobar") {
    13. Ok(n) => println!("{}", n),
    14. Err(err) => println!("Error: {}", err),
    15. }
    16. }

    根据我们try!宏的定义map_err调用仍是必要的。这是因为错误类型仍然需要被转换为String。好消息是我们马上就会学到如何移除这些map_err调用!坏消息是在我们可以移除map_err调用之前我们需要更深入的学习一些标准库中的重要的 trait。

    定义你自己的错误类型" class="reference-link">定义你自己的错误类型

    在我们深入学习一些标准库错误 trait 之前,我想要通过移除之前例子中的作为错误类型的String来结束本章节。

    之前我们的例子中使用String是为了方便,因为把错误转换为字符串是简单的,甚至把我们自己的类型转换为字符串也是如此。然而,把String作为你的错误有一些缺点。

    第一个缺点是错误信息会倾向于另你的代码变得凌乱。把错误信息定义在别处是可能的,不顾除非你非常的(qiang)自(po)律(zheng),你很容易就会把错误信息嵌入到你的代码中。事实上,我们上一个例子就是这么做的。

    第二个也是更重要的缺点是String不完整的。也就是说,如果所有错误都转换成了字符串,那么传递给调用者的错误就变得完全不透明了。调用者对于一个String类型的错误所能作的唯一可行的事就是把它展示给用户。当然,通过观察字符串来确定错误的类型是不健壮的。(对于一个库来说这个缺点公认要比在例如程序中来的更重要。)

    例如,io::Error类型内嵌了一个io::ErrorKind,它是一个表示在 IO 操作期间错误信息的结构化类型。这很重要因为你可能根据错误做出不同的反应。(例如,BrokenPipe错误可能意味着可以温和的退出程序,而NotFound则意味着应该返回一个错误码并向用户展示错误。)通过io::ErrorKind,调用者可以用 case analysis 检查错误的类型,这完全优于尝试从String中梳理错误的细节。

    除了在我们之前从文件读取一个数字的例子中使用String作为错误类型外,我们可以定义我们自己的错误类型来用结构化数据代表错误。我们尽量不丢掉底层错误的信息以防调用者想要检视细节。

    表示多种可能性的理想方法是用enum来定义我们的集合类型。在我们的例子里,错误要么是io::Error要么是num::ParseIntError,所以自然的定义如下:

    1. use std::io;
    2. use std::num;
    3. // We derive `Debug` because all types should probably derive `Debug`.
    4. // This gives us a reasonable human readable description of `CliError` values.
    5. #[derive(Debug)]
    6. enum CliError {
    7. Io(io::Error),
    8. Parse(num::ParseIntError),
    9. }

    修改我们代码非常简单。与其把错误转为字符串,我们简单的用相应的值构造器把错误转换为我们的CliError类型:

    1. # #[derive(Debug)]
    2. # enum CliError { Io(::std::io::Error), Parse(::std::num::ParseIntError) }
    3. use std::fs::File;
    4. use std::io::Read;
    5. use std::path::Path;
    6. fn file_double<P: AsRef<Path>>(file_path: P) -> Result<i32, CliError> {
    7. let mut file = try!(File::open(file_path).map_err(CliError::Io));
    8. let mut contents = String::new();
    9. try!(file.read_to_string(&mut contents).map_err(CliError::Io));
    10. let n: i32 = try!(contents.trim().parse().map_err(CliError::Parse));
    11. Ok(2 * n)
    12. }
    13. fn main() {
    14. match file_double("foobar") {
    15. Ok(n) => println!("{}", n),
    16. Err(err) => println!("Error: {:?}", err),
    17. }
    18. }

    这里唯一的修改是从map_err(|e| e.to_string())(它把错误转换为字符串)变为map_err(CliError::Io)或者map_err(CliError::Parse)。调用者要决定报告给用户的细节的级别。实际上,使用String作为错误类型剥夺了调用者的选择,而用一个像CliError这样的enum类型除了一个描述错误的结构化数据之外还给了调用者所有的便利。

    经验之谈是定义你自己的错误类型,不过必要时String也能行,特别是你在写一个程序时。如果你在编写一个库,强烈建议你定义自己的错误类型这样你就不会不必要的剥夺了调用者选择。

    用于错误处理的标准库 trait" class="reference-link">用于错误处理的标准库 trait

    标准库定义了两个完整 trait 用于错误处理::Error">http://doc.rust-lang.org/std/error/trait.Error.htmlstd::convert::FromError被专门设计为描述通用错误,From trait 更多的用于在两个不同类型值之间转换。

    Errortrait" class="reference-link">Errortrait

    Error trait 定义于标准库中

    1. use std::fmt::{Debug, Display};
    2. trait Error: Debug + Display {
    3. /// A short description of the error.
    4. fn description(&self) -> &str;
    5. /// The lower level cause of this error, if any.
    6. fn cause(&self) -> Option<&Error> { None }
    7. }

    这个 trait 非常泛用因为它被设计为为所有类型实现来代表错误。它被证明对编写可组合的代码非常有帮助,正如我们后面将要看到的。这个 trait 允许你至少做如下事情:

    • 获取一个错误的Debug表示。
    • 获取一个错误的面向用户的Display表示
    • 获取一个错误的简短描述(通过description方法)
    • 查看错误的调用链,如果存在的话(通过cause方法)

    头两个是因为Error要求实现DebugDisplay。后两个来自于定义于Error的方法。Error的力量来自于所有错误类型都实现了Error的事实,这意味着错误可以被量化一个trait 对象。表现为Box<Error>&Error。事实上,cause返回一个&Error,它自身就是一个 trait 对象。我们将在后面再次讨论Error作为 trait 对象的功能。

    目前,展示一个实现了Error trait 的例子是足够的。让我们使用上一部分我们定义的错误类型:

    1. use std::io;
    2. use std::num;
    3. // We derive `Debug` because all types should probably derive `Debug`.
    4. // This gives us a reasonable human readable description of `CliError` values.
    5. #[derive(Debug)]
    6. enum CliError {
    7. Io(io::Error),
    8. Parse(num::ParseIntError),
    9. }

    这个特定的错误类型表示出现两种错误类型的可能性:一个进行 I/O 操作的错误或者一个把字符串转换为数字的错误。这个类型可以表示任何你想要添加的错误类型,通过向enum定义添加变量。

    实现Error是非常直观的。这会有很多的显式 case analysis。

    1. use std::error;
    2. use std::fmt;
    3. impl fmt::Display for CliError {
    4. fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
    5. match *self {
    6. // Both underlying errors already impl `Display`, so we defer to
    7. // their implementations.
    8. CliError::Io(ref err) => write!(f, "IO error: {}", err),
    9. CliError::Parse(ref err) => write!(f, "Parse error: {}", err),
    10. }
    11. }
    12. }
    13. impl error::Error for CliError {
    14. fn description(&self) -> &str {
    15. // Both underlying errors already impl `Error`, so we defer to their
    16. // implementations.
    17. match *self {
    18. CliError::Io(ref err) => err.description(),
    19. CliError::Parse(ref err) => err.description(),
    20. }
    21. }
    22. fn cause(&self) -> Option<&error::Error> {
    23. match *self {
    24. // N.B. Both of these implicitly cast `err` from their concrete
    25. // types (either `&io::Error` or `&num::ParseIntError`)
    26. // to a trait object `&Error`. This works because both error types
    27. // implement `Error`.
    28. CliError::Io(ref err) => Some(err),
    29. CliError::Parse(ref err) => Some(err),
    30. }
    31. }
    32. }

    我们注意到这是一个非常典型的Error的实现:为你不同的错误类型做匹配并满足descriptioncause定义的限制。

    Fromtrait" class="reference-link">Fromtrait

    std::convert::From trait 定义于标准库中

    1. trait From<T> {
    2. fn from(T) -> Self;
    3. }

    非常简单吧?From很有用因为它给了我们一个通用的方式来处理从一个特定类型T到其他类型的转换(在这个例子中,“其他类型”是实现的主体,或者Self)。From的核心是标准库提供的一系列实现

    这里是几个展示From如何工作的小例子:

    1. let string: String = From::from("foo");
    2. let bytes: Vec<u8> = From::from("foo");
    3. let cow: ::std::borrow::Cow<str> = From::from("foo");

    好的,这么说From用来处理字符串转换,那么错误怎么办?原来有一个关键实现:

    1. impl<'a, E: Error + 'a> From<E> for Box<Error + 'a>

    这个实现说任何实现了Error的类型,我们可以把它转换一个 trait 对象Box<Error>。这可能看起来并不怎么令人吃惊,不过它在泛型环境中很有用。

    记得我们之前处理的两个错误吗?io::Errornum::ParseIntError。因为他们都实现了Error,他们也能用于From

    1. use std::error::Error;
    2. use std::fs;
    3. use std::io;
    4. use std::num;
    5. // We have to jump through some hoops to actually get error values:
    6. let io_err: io::Error = io::Error::last_os_error();
    7. let parse_err: num::ParseIntError = "not a number".parse::<i32>().unwrap_err();
    8. // OK, here are the conversions:
    9. let err1: Box<Error> = From::from(io_err);
    10. let err2: Box<Error> = From::from(parse_err);

    这里有一个非常重要的模式。err1err2有着相同的类型。这是因为他们实际上是定量类型,或者 trait 对象。尤其是,对编译器来说他们的底层类型被抹掉了,所以编译器认为err1err2是完全一样的。另外,我们用完全一样的函数调用构建err1err2From::from。这是因为From::from的参数和返回值都可以重载。

    这个模式很重要,因为它解决了一个我们之前遇到过的问题:它给了我们一个可靠的用相同的函数把错误转换为相同类型的方法。

    是时候重新看看我们的老朋友:try!宏了。

    真正的try!宏" class="reference-link">真正的try!

    之前我们展示了try!的定义:

    1. macro_rules! try {
    2. ($e:expr) => (match $e {
    3. Ok(val) => val,
    4. Err(err) => return Err(err),
    5. });
    6. }

    这并不是它真正的定义。它的实际定义位于标准库中

    1. macro_rules! try {
    2. ($e:expr) => (match $e {
    3. Ok(val) => val,
    4. Err(err) => return Err(::std::convert::From::from(err)),
    5. });
    6. }

    这是一个很小但很有效的修改:错误值被通过From::from传递。这让try!宏变得更强大了一点,因为它免费提供给你自动类型转换。

    有了更强大的try!宏的支持,让我们再看一眼我们之前写的读一个文件并把内容转换为数字的代码:

    1. use std::fs::File;
    2. use std::io::Read;
    3. use std::path::Path;
    4. fn file_double<P: AsRef<Path>>(file_path: P) -> Result<i32, String> {
    5. let mut file = try!(File::open(file_path).map_err(|e| e.to_string()));
    6. let mut contents = String::new();
    7. try!(file.read_to_string(&mut contents).map_err(|e| e.to_string()));
    8. let n = try!(contents.trim().parse::<i32>().map_err(|e| e.to_string()));
    9. Ok(2 * n)
    10. }

    之前,我们承诺我们可以去掉map_err调用。实际上,所有我们需要做的就是选一个可以用于From的类型。一如我们在上一个部分看到的,From有一个可以转换任意错误类型为Box<Error>的实现:

    1. use std::error::Error;
    2. use std::fs::File;
    3. use std::io::Read;
    4. use std::path::Path;
    5. fn file_double<P: AsRef<Path>>(file_path: P) -> Result<i32, Box<Error>> {
    6. let mut file = try!(File::open(file_path));
    7. let mut contents = String::new();
    8. try!(file.read_to_string(&mut contents));
    9. let n = try!(contents.trim().parse::<i32>());
    10. Ok(2 * n)
    11. }

    我们已经非常接近理想的错误处理了。我们的代码处理错误只造成了很小的成本,因为try!宏同时封装了三个东西:

    1. case analysis。
    2. 控制流。
    3. 错误类型转换。

    当结合所有这些东西,我们的代码不再受组合、unwrap调用或 case analysis 的困扰了。

    这里还剩一点东西:Box<Error>是不透明的。如果我们返回一个Box<Error>给调用者,调用者并不能(轻易地)观察底层错误类型。当然这种情形比String要好,因为调用者可以调用像descriptioncause这样的方法,不过这是有限制的:Box<Error>是不透明的。(附注:这并不是完全正确,因为 Rust 并没有运行时反射,这在某些场景是有用的不过超出了本部分的范畴。)

    是时候重写我们的CliError类型并将一切连起来了。

    组合自定义错误类型" class="reference-link">组合自定义错误类型

    在这最后一部分,我们看看真正的try!宏以及如何通过调用From::from自动转换错误类型。具体的,我们把错误转换为Box<Error>,这是可以的,不过这个类型对调用者是不透明的。

    为了修改这个问题,我们使用我们已经熟知的补救方法:一个自定义错误类型。再一次,这是读取文件内容并将其转换为数字的代码:

    1. use std::fs::File;
    2. use std::io::{self, Read};
    3. use std::num;
    4. use std::path::Path;
    5. // We derive `Debug` because all types should probably derive `Debug`.
    6. // This gives us a reasonable human readable description of `CliError` values.
    7. #[derive(Debug)]
    8. enum CliError {
    9. Io(io::Error),
    10. Parse(num::ParseIntError),
    11. }
    12. fn file_double_verbose<P: AsRef<Path>>(file_path: P) -> Result<i32, CliError> {
    13. let mut file = try!(File::open(file_path).map_err(CliError::Io));
    14. let mut contents = String::new();
    15. try!(file.read_to_string(&mut contents).map_err(CliError::Io));
    16. let n: i32 = try!(contents.trim().parse().map_err(CliError::Parse));
    17. Ok(2 * n)
    18. }

    注意我们仍然有map_err的调用。为神马?好吧,回忆try!From的定义。问题是这里并没有impl的实现允许我们将一些像io::Errornum::ParseIntError这样的错误类型转换为我们的自定义类型CliError。当然,这个问题很好修改!CliError都是我们定义的,我们可以为其实现From

    1. # #[derive(Debug)]
    2. # enum CliError { Io(io::Error), Parse(num::ParseIntError) }
    3. use std::io;
    4. use std::num;
    5. impl From<io::Error> for CliError {
    6. fn from(err: io::Error) -> CliError {
    7. CliError::Io(err)
    8. }
    9. }
    10. impl From<num::ParseIntError> for CliError {
    11. fn from(err: num::ParseIntError) -> CliError {
    12. CliError::Parse(err)
    13. }
    14. }

    所有这些实现都是告诉From如何从其他类型创建一个CliError。在我们的例子中,构造函数就像调用相应的值构造器那样简单。确实,这通常很简单。

    最后我们可以重写file_double

    1. # use std::io;
    2. # use std::num;
    3. # enum CliError { Io(::std::io::Error), Parse(::std::num::ParseIntError) }
    4. # impl From<io::Error> for CliError {
    5. # fn from(err: io::Error) -> CliError { CliError::Io(err) }
    6. # }
    7. # impl From<num::ParseIntError> for CliError {
    8. # fn from(err: num::ParseIntError) -> CliError { CliError::Parse(err) }
    9. # }
    10. use std::fs::File;
    11. use std::io::Read;
    12. use std::path::Path;
    13. fn file_double<P: AsRef<Path>>(file_path: P) -> Result<i32, CliError> {
    14. let mut file = try!(File::open(file_path));
    15. let mut contents = String::new();
    16. try!(file.read_to_string(&mut contents));
    17. let n: i32 = try!(contents.trim().parse());
    18. Ok(2 * n)
    19. }

    我们做的唯一一件事就是去掉了map_err调用。他们不再必要因为try!宏对错误类型调用了From::from。这一切可以工作因为我们对所有可能出现的错误类型提供了From实现。

    如果我们修改我们的file_double函数来进行一些其他操作,例如,把字符串转换为浮点数,那么我们需要给我们的错误类型增加一个新变量:

    1. use std::io;
    2. use std::num;
    3. enum CliError {
    4. Io(io::Error),
    5. ParseInt(num::ParseIntError),
    6. ParseFloat(num::ParseFloatError),
    7. }

    并增加一个新的From实现:

    1. # enum CliError {
    2. # Io(::std::io::Error),
    3. # ParseInt(num::ParseIntError),
    4. # ParseFloat(num::ParseFloatError),
    5. # }
    6. use std::num;
    7. impl From<num::ParseFloatError> for CliError {
    8. fn from(err: num::ParseFloatError) -> CliError {
    9. CliError::ParseFloat(err)
    10. }
    11. }

    一切搞定!

    给库编写者的建议" class="reference-link">给库编写者的建议

    如果你的库需要报告一些自定义错误,那么你可能应该定义你自己的错误类型。由你决定是否暴露它的表示(例如ErrorKind)或者把它隐藏起来(例如ParseIntError)。不过你怎么做,相比String表示多少提供一些关于错误的信息通常是好的实践。不过说实话,这根据使用情况大有不同。

    最少,你可能应该实现Errortrait。这会给你的库的用户以处理错误的最小灵活性。实现Errortrait 也意味着可以确保用户能够获得一个错误的字符串表示(因为它实现了fmt::Debugfmt::Display)。

    不仅如此,为你的错误类型提供From实现也是很有用的。这允许你(库作者)和你的用户组合更详细的错误。例如,csv::Error提供了io::Errorbyteorder::Error

    最后,根据你的风格,你也许想要定义一个Result类型别名,尤其是如果你的库定义了一个单一的错误类型。这被用在了标准库的io::Resultfmt::Result中。

    案例学习:一个读取人口数据的程序" class="reference-link">案例学习:一个读取人口数据的程序

    这一部分很长,并且根据你的背景,它可能显得更加复杂。虽然有很多示例代码以及散文一样的解释,但大部分都被设计为教科书式的。那么,我们要开始点新东西了:一个案例学习。

    为此,为此我们将要建立一个可以让你查询真实世界人口数据的命令行程序。目标是简单的:你给出一个地点接着它会告诉你人口。虽然这很简单,但仍有很多地方我们可能犯错。

    我们将使用的数据来自Data Science Toolkit。我为这个练习准备了一些数据。你要么可以获取世界人口数据(41 MB gzip 压缩,145 MB 未压缩)或者只使用US 人口数据(2.2 MB gzip 压缩,7.2 MB 未压缩)。

    直到目前为止,我们的代码一直限制在 Rust 标准库之内。但是对于一个像这样的真实的任务,我们至少想要一些解析 CSV 数据,解析程序参数以及将其自动转换为 Rust 类型的东西。为此,我们将使用csv,以及rustc-serializecrate。

    初始化" class="reference-link">初始化

    我们不打算花很多时间在使用 Cargo 创建一个项目上,因为这在 Cargo 部分Cargo 文档中已被讲解。

    为了从头开始,运行cargo new --bin city-pop并确保你的Cargo.toml看起来像这样:

    1. [package]
    2. name = "city-pop"
    3. version = "0.1.0"
    4. authors = ["Andrew Gallant <jamslam@gmail.com>"]
    5. [[bin]]
    6. name = "city-pop"
    7. [dependencies]
    8. csv = "0.*"
    9. rustc-serialize = "0.*"
    10. getopts = "0.*"

    你应该已经可以运行了:

    1. cargo build --release
    2. ./target/release/city-pop
    3. # Outputs: Hello, world!

    参数解析" class="reference-link">参数解析

    让我们搞定参数解析,我们不会涉及太多关于 Getopts 的细节,不过有一些不错的文档。简单的说就是 Getopts 生成了一个参数解析器并通过要给选项的 vector(事实是一个隐藏于一个结构体和一堆方法之下的 vector)生成了一个帮助信息。一旦解析结束,解析器返回一个记录了匹配到定义项内容的结构体,和剩下“自由”的参数。从这里我们可以互获取 flag,实例,任何程序传递给我们的,以及他们都有什么参数。这是我们的程序,它有合适的extern crate语句以及 Getopts 的基本参数操作:

    1. extern crate getopts;
    2. extern crate rustc_serialize;
    3. use getopts::Options;
    4. use std::env;
    5. fn print_usage(program: &str, opts: Options) {
    6. println!("{}", opts.usage(&format!("Usage: {} [options] <data-path> <city>", program)));
    7. }
    8. fn main() {
    9. let args: Vec<String> = env::args().collect();
    10. let program = &args[0];
    11. let mut opts = Options::new();
    12. opts.optflag("h", "help", "Show this usage message.");
    13. let matches = match opts.parse(&args[1..]) {
    14. Ok(m) => { m }
    15. Err(e) => { panic!(e.to_string()) }
    16. };
    17. if matches.opt_present("h") {
    18. print_usage(&program, opts);
    19. return;
    20. }
    21. let data_path = &matches.free[0];
    22. let city: &str = &matches.free[1];
    23. // Do stuff with information.
    24. }

    首先,我们获取一个传递给我们程序的 vector。接着我们我们储存第一个参数,因为我们知道那是程序名。当一切搞定,我们设置我们的参数 flag,在这里是一个简单的提示信息 flag。当我们设置了参数 flag 之后,我们使用Options.parse解析参数列表(从 1 开始,因为 0 是程序名)。如果这成功了,我们被解析的对象赋值给matches,如果失败了,我们 panic。接着,我们检查用户是否传递了帮助 flag,如果是就打印使用帮助信息。帮助信息选项是 Getopts 构建的,所以为了打印用法信息所有我们需要做的就是告诉它我们想要打印什么名字和模板。如果用户并没有传递帮助 flag,我们把相应的参数赋值给合适的变量。

    编写逻辑" class="reference-link">编写逻辑

    每个人写代码的方式各有不同,不过一般错误处理都是我们最后会思考的事情。这对程序整体的设计并不好,不过它对快速原型有帮助。因为 Rust 强制我们进行显示的错误处理(通过让我们调用unwrap),这样很容易看出我们的程序的那一部分可以造成错误。

    在这个案例学习中,逻辑真的很简单。所有我们要做的就是解析给我们的 CSV 数据并打印出匹配的行的一个字段。让我们开始吧。(确保在你的文件开头加上extern crate csv;。)

    1. use std::fs::File;
    2. // This struct represents the data in each row of the CSV file.
    3. // Type based decoding absolves us of a lot of the nitty gritty error
    4. // handling, like parsing strings as integers or floats.
    5. #[derive(Debug, RustcDecodable)]
    6. struct Row {
    7. country: String,
    8. city: String,
    9. accent_city: String,
    10. region: String,
    11. // Not every row has data for the population, latitude or longitude!
    12. // So we express them as `Option` types, which admits the possibility of
    13. // absence. The CSV parser will fill in the correct value for us.
    14. population: Option<u64>,
    15. latitude: Option<f64>,
    16. longitude: Option<f64>,
    17. }
    18. fn print_usage(program: &str, opts: Options) {
    19. println!("{}", opts.usage(&format!("Usage: {} [options] <data-path> <city>", program)));
    20. }
    21. fn main() {
    22. let args: Vec<String> = env::args().collect();
    23. let program = &args[0];
    24. let mut opts = Options::new();
    25. opts.optflag("h", "help", "Show this usage message.");
    26. let matches = match opts.parse(&args[1..]) {
    27. Ok(m) => { m }
    28. Err(e) => { panic!(e.to_string()) }
    29. };
    30. if matches.opt_present("h") {
    31. print_usage(&program, opts);
    32. return;
    33. }
    34. let data_path = &matches.free[0];
    35. let city: &str = &matches.free[1];
    36. let file = File::open(data_path).unwrap();
    37. let mut rdr = csv::Reader::from_reader(file);
    38. for row in rdr.decode::<Row>() {
    39. let row = row.unwrap();
    40. if row.city == city {
    41. println!("{}, {}: {:?}",
    42. row.city, row.country,
    43. row.population.expect("population count"));
    44. }
    45. }
    46. }

    让我们概括下错误。我们可以从明显的开始:三个unwrap被调用的地方:

    1. File::open可能返回io::Error
    2. csv::Reader::decode一次解码一行,而且解码一个记录(查看Iterator实现的关联类型Item)可能产生一个csv::Error

    3. 如果row.populationNone,那么调用expect会 panic。

    还有其他的吗?如果我们无法找到一个匹配的城市呢?想grep这样的工具会返回一个错误码,所以可能我们也应该这么做。所以我们有特定于我们的问题,IO 错误和 CSV 解析错误的逻辑错误。我们将探索两个不同方式来处理这个问题。

    我像从Box<Error>开始。接着,我们看看如何定义有用的自定义错误类型。

    使用Box<Error>处理错误" class="reference-link">使用Box<Error>处理错误

    Box<Error>的好处是它刚刚够用。你并不需要定义你自己的错误类型而且也不需要任何From实现。缺点是因为Box<Error>是一个 trait 对象,这意味着编译器无法再推导出底层类型。

    之前我们开始了把我们函数类型从T变成Result<T, OurErrorType>的重构。在这个例子中,OurErrorType就是Box<Error>。不过T是什么?或者我们可以给main添加一个返回类型吗?

    第二个问题的答案是不行,我们不能这么做。这意味着我们需要写一个新函数。不过T是什么?最简单的办法是返回一个作为Vec<Row>的匹配上的Row的值。(更好的代码会返回一个迭代器,不过这是一个留给读者的练习。)

    让我们重构函数,不过保持对unwrap的调用。注意我们选择处理一个不存在的人口数行的方式是单纯的忽略它。

    1. use std::path::Path;
    2. struct Row {
    3. // This struct remains unchanged.
    4. }
    5. struct PopulationCount {
    6. city: String,
    7. country: String,
    8. // This is no longer an `Option` because values of this type are only
    9. // constructed if they have a population count.
    10. count: u64,
    11. }
    12. fn print_usage(program: &str, opts: Options) {
    13. println!("{}", opts.usage(&format!("Usage: {} [options] <data-path> <city>", program)));
    14. }
    15. fn search<P: AsRef<Path>>(file_path: P, city: &str) -> Vec<PopulationCount> {
    16. let mut found = vec![];
    17. let file = File::open(file_path).unwrap();
    18. let mut rdr = csv::Reader::from_reader(file);
    19. for row in rdr.decode::<Row>() {
    20. let row = row.unwrap();
    21. match row.population {
    22. None => { } // Skip it.
    23. Some(count) => if row.city == city {
    24. found.push(PopulationCount {
    25. city: row.city,
    26. country: row.country,
    27. count: count,
    28. });
    29. },
    30. }
    31. }
    32. found
    33. }
    34. fn main() {
    35. let args: Vec<String> = env::args().collect();
    36. let program = &args[0];
    37. let mut opts = Options::new();
    38. opts.optflag("h", "help", "Show this usage message.");
    39. let matches = match opts.parse(&args[1..]) {
    40. Ok(m) => { m }
    41. Err(e) => { panic!(e.to_string()) }
    42. };
    43. if matches.opt_present("h") {
    44. print_usage(&program, opts);
    45. return;
    46. }
    47. let data_path = &matches.free[0];
    48. let city: &str = &matches.free[1];
    49. for pop in search(data_path, city) {
    50. println!("{}, {}: {:?}", pop.city, pop.country, pop.count);
    51. }
    52. }

    虽然我们去掉了一个expect调用(它是一个比unwrap要好的变体),我们仍要处理任何不存在的搜索结果。

    为了把这转化为合适的错误处理,我们需要做如下事情:

    1. search的返回值类型改为Result<Vec<PopulationCount>, Box<Error>>.
    2. 使用try!这样会返回错误给调用者而不是使程序 panic。
    3. 处理mian中的错误。

    让我们试试:

    1. use std::error::Error;
    2. // The rest of the code before this is unchanged.
    3. fn search<P: AsRef<Path>>
    4. (file_path: P, city: &str)
    5. -> Result<Vec<PopulationCount>, Box<Error>> {
    6. let mut found = vec![];
    7. let file = try!(File::open(file_path));
    8. let mut rdr = csv::Reader::from_reader(file);
    9. for row in rdr.decode::<Row>() {
    10. let row = try!(row);
    11. match row.population {
    12. None => { } // Skip it.
    13. Some(count) => if row.city == city {
    14. found.push(PopulationCount {
    15. city: row.city,
    16. country: row.country,
    17. count: count,
    18. });
    19. },
    20. }
    21. }
    22. if found.is_empty() {
    23. Err(From::from("No matching cities with a population were found."))
    24. } else {
    25. Ok(found)
    26. }
    27. }

    现在我们用try!(x)代替了x.unwrap()。因为我们的函数返回一个Result<T, E>try!宏在出现错误时会提早返回。

    search的结尾我们也用了相应的From实现把一个字符串转换为一个错误类型:

    1. // We are making use of this impl in the code above, since we call `From::from`
    2. // on a `&'static str`.
    3. impl<'a> From<&'a str> for Box<Error>
    4. // But this is also useful when you need to allocate a new string for an
    5. // error message, usually with `format!`.
    6. impl From<String> for Box<Error>

    因为search现在返回Result<T, E>main应该在调用search时使用 case analysis:

    1. ...
    2. match search(data_path, city) {
    3. Ok(pops) => {
    4. for pop in pops {
    5. println!("{}, {}: {:?}", pop.city, pop.country, pop.count);
    6. }
    7. }
    8. Err(err) => println!("{}", err)
    9. }
    10. ...

    现在你看到了我们如何正确的处理Box<Error>,让我们尝试一种使用我们自定义错误类型的不同方式。不过首先,让我们先放下错误处理并快速的添加从stdin读取的功能。

    从标准输入读取" class="reference-link">从标准输入读取

    在我们的程序中,我们接受一个单文件输入并进行一次数据解析。这意味着我们可能需要能够接受标准输入。不过你可能也喜欢现在的格式——所以让我们同时拥有两者吧!

    添加标准输入支持是非常简单的。我们只必需做三件事:

    1. 修改程序参数,这样一个单独的参数——城市——可以被接受,同时人口数据从标准输入读取。
    2. 修改程序,这样一个-f选项可以接受文件,如果它没有从标准输入传递。
    3. 修改search函数接受一个可选的文件路径。当为None时,它应该知道从标准输入读取。

    首先,这是新的使用方法函数:

    1. fn print_usage(program: &str, opts: Options) {
    2. println!("{}", opts.usage(&format!("Usage: {} [options] <city>", program)));
    3. }

    当然我们需要加入参数处理的代码:

    1. ...
    2. let mut opts = Options::new();
    3. opts.optopt("f", "file", "Choose an input file, instead of using STDIN.", "NAME");
    4. opts.optflag("h", "help", "Show this usage message.");
    5. ...
    6. let data_path = matches.opt_str("f");
    7. let city = if !matches.free.is_empty() {
    8. &matches.free[0]
    9. } else {
    10. print_usage(&program, opts);
    11. return;
    12. };
    13. match search(&data_path, city) {
    14. Ok(pops) => {
    15. for pop in pops {
    16. println!("{}, {}: {:?}", pop.city, pop.country, pop.count);
    17. }
    18. }
    19. Err(err) => println!("{}", err)
    20. }
    21. ...

    我们已经通过显示使用方法信息来提高了用户体验,而不是因为city这个额外的参数不存在导致索引越界而 panic,

    修改search需要一点技巧。csvcrate 可以用任何实现了io::Read的类型构建一个解析器。不过我们如何对这两个类型(注:因该是Option的两个值)使用相同的代码呢?事实上有多种方法可以做到。其中之一是重写search为接受一个满足io::ReadR类型参数的泛型。另一个办法是使用 trait 对象:

    1. use std::io;
    2. // The rest of the code before this is unchanged.
    3. fn search<P: AsRef<Path>>
    4. (file_path: &Option<P>, city: &str)
    5. -> Result<Vec<PopulationCount>, Box<Error>> {
    6. let mut found = vec![];
    7. let input: Box<io::Read> = match *file_path {
    8. None => Box::new(io::stdin()),
    9. Some(ref file_path) => Box::new(try!(File::open(file_path))),
    10. };
    11. let mut rdr = csv::Reader::from_reader(input);
    12. // The rest remains unchanged!
    13. }

    用自定义类型处理错误" class="reference-link">用自定义类型处理错误

    之前,我们学习了如何用自定义错误类型组合错误。我们定义了一个enum的错误类型并实现了ErrorFrom

    因为我们有三个不同的错误(IO,CSV 解析和未找到),让我们定义一个三个变体的enum

    1. #[derive(Debug)]
    2. enum CliError {
    3. Io(io::Error),
    4. Csv(csv::Error),
    5. NotFound,
    6. }

    现在让我们实现DisplayError

    1. use std::fmt;
    2. impl fmt::Display for CliError {
    3. fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
    4. match *self {
    5. CliError::Io(ref err) => err.fmt(f),
    6. CliError::Csv(ref err) => err.fmt(f),
    7. CliError::NotFound => write!(f, "No matching cities with a \
    8. population were found."),
    9. }
    10. }
    11. }
    12. impl Error for CliError {
    13. fn description(&self) -> &str {
    14. match *self {
    15. CliError::Io(ref err) => err.description(),
    16. CliError::Csv(ref err) => err.description(),
    17. CliError::NotFound => "not found",
    18. }
    19. }
    20. fn cause(&self) -> Option<&Error> {
    21. match *self {
    22. CliError::Io(ref err) => Some(err),
    23. CliError::Csv(ref err) => Some(err),
    24. // Our custom error doesn't have an underlying cause,
    25. // but we could modify it so that it does.
    26. CliError::NotFound => None,
    27. }
    28. }
    29. }

    在我们可以在search函数中使用CliError之前,我们需要提供一系列的From实现。我们如何知晓该提供那个实现呢?好吧,我们得把io::Errorcsv::Error都转换为CliError。他们都只是外部错误,所以目前我们只需要两个From实现:

    1. impl From<io::Error> for CliError {
    2. fn from(err: io::Error) -> CliError {
    3. CliError::Io(err)
    4. }
    5. }
    6. impl From<csv::Error> for CliError {
    7. fn from(err: csv::Error) -> CliError {
    8. CliError::Csv(err)
    9. }
    10. }

    因为try!的定义From的实现是很重要的。尤其是在这个例子中,如果出现错误,错误的From::from被调用,将被转换为我们的错误类型CliError

    当实现了From,我们只需要对search函数进行两个小的修改:返回值类型和“未找到”错误。这是全部的代码:

    1. fn search<P: AsRef<Path>>
    2. (file_path: &Option<P>, city: &str)
    3. -> Result<Vec<PopulationCount>, CliError> {
    4. let mut found = vec![];
    5. let input: Box<io::Read> = match *file_path {
    6. None => Box::new(io::stdin()),
    7. Some(ref file_path) => Box::new(try!(File::open(file_path))),
    8. };
    9. let mut rdr = csv::Reader::from_reader(input);
    10. for row in rdr.decode::<Row>() {
    11. let row = try!(row);
    12. match row.population {
    13. None => { } // Skip it.
    14. Some(count) => if row.city == city {
    15. found.push(PopulationCount {
    16. city: row.city,
    17. country: row.country,
    18. count: count,
    19. });
    20. },
    21. }
    22. }
    23. if found.is_empty() {
    24. Err(CliError::NotFound)
    25. } else {
    26. Ok(found)
    27. }
    28. }

    不再需要其他的修改。

    增加功能" class="reference-link">增加功能

    编写泛型代码是很好的,因为泛用性是很酷的,并且之后会变得很有用。不过有时并不值得这么做。看看我们上一部分我们是怎么做的:

    1. 定义了一个新的错误类型。
    2. 增加ErrorDisplay和两个From实现。

    这里最大的缺点是我们的程序并没有改进多少。这里仍然有很多用enum代表错误的额外操作,特别是在这样短小的程序里。

    像我们这样使用自定义错误类型的一个有用的方面是main函数现在可以选择不同的处理错误的方式。之前使用Box<Error>的时候并没有什么选择:只能打印信息。我们现在仍可以这么做,不过只是在我们想这么做的时候,例如,添加一个--quiet flag?--quiet flag 应该能够消除任何冗余的输出。

    现在如果程序不能匹配一个城市,它会打印一个信息说它不能。这可能有点蠢,尤其是你想要你的程序能在 shell 脚本中使用的时候。

    所以让我们开始增加 flag。就像之前一样,我们需要修改用法字符串,并给选项变量添加 flag。当我们写完这些,Getopts 会搞定剩下的操作:

    1. ...
    2. let mut opts = Options::new();
    3. opts.optopt("f", "file", "Choose an input file, instead of using STDIN.", "NAME");
    4. opts.optflag("h", "help", "Show this usage message.");
    5. opts.optflag("q", "quiet", "Silences errors and warnings.");
    6. ...

    现在我们只需要实现我们的“安静”功能。这要求我们修改mian中的 case analysis:

    1. use std::process;
    2. ...
    3. match search(&data_path, city) {
    4. Err(CliError::NotFound) if matches.opt_present("q") => process::exit(1),
    5. Err(err) => panic!("{}", err),
    6. Ok(pops) => for pop in pops {
    7. println!("{}, {}: {:?}", pop.city, pop.country, pop.count);
    8. }
    9. }
    10. ...

    当然,在出现 IO 错误或者数据解析失败时我们并不想变得安静。因此,我们用 case analysis 来检查错误类型是否是NotFound以及--quiet是否被启用。如果,搜索失败了,我们仍然使用一个错误码退出(使用grep的传统)。

    如果我们还在用Box<Error>,那么实现--quiet功能将变得很复杂。

    我们的案例学习讲了很多东西。从这时起,你应该能够在现实生活中编写带有合适错误处理的程序和库了。

    精简版" class="reference-link">精简版

    因为这个章节很长,有一个 Rust 错误处理的快速总结是很有帮助的。有很多好的“经验规则”。需要强调的是他们并非教条。这里每一个建议都可能有适当的理由予以反驳!

    • 如果你在写小的事例代码这时错误处理显得负担过重,可能使用unwrapResult::unwrapOption::unwrap,或是更可取的Option::expect)是足够的。你的代码的客户应该知道如何正确的处理错误。(如果他们并不知道,教会他们吧!)

    • 如果你在 hack(quick ‘n’ dirty)程序,不要为你使用unwrap而感羞愧。不过你被警告过了:如果别人踩到了坑,不要因为他们对糟糕的错误信息火冒三丈而感到惊讶!

    • 如果你在 hack 程序并对 panic 感到羞愧,那么使用String或者Box<Error>作为你的错误类型。

    • 否则,在程序中,定义你自己的错误类型并实现合适的FromError来让try!宏变得更工程化。

    • 如果你在写一个库并且它可能产生错误,定义你自己的错误类型并实现std::error::Error trait。如果可以的话,实现From来让你的库代码和调用者的代码更加容易编写。(因为 Rust 的一致性规则,调用者不能为你的错误类型实现From,所以你的库应该实现。)

    • 学习定义于OptionResult中的组合。只使用他们有时可能比较累人,不过我个人发现合理的结合try!和组合是比较诱人的。and_thenmapunwrap_or是我们的最爱。